…API-238)

BUG-API-238 — the free-tier recycle gate emits 402
`free_tier_recycle_requires_claim` with a claim_url the user can act on in
30 seconds. Pre-fix the 402 was written to the explicit-key 24h cache, so
this sequence stranded the agent on a stale failure:

  1. Agent POST /db/new with Idempotency-Key K1 → 402 (cached against K1).
  2. User follows claim_url, claims with email (clears the gate state).
  3. Agent retries POST /db/new with K1 → replays the cached 402.

The 24h cache TTL is the Stripe contract — same key replays the same
response — but it presumes a STABLE outcome. A 402 that flips when the
user takes a 30-second action is not stable.

Fix:
  - mutableErrorCodes registry (currently { free_tier_recycle_requires_claim })
    listing error codes whose 4xx resolution can flip inside the cache TTL.
  - shouldCacheResponse(status, body, ct) helper that defers to caching for
    success + non-JSON + stable 4xx, but skips for body.error ∈ mutable map.
  - Wired into BOTH explicit-key (24h TTL) and fingerprint-fallback (120s)
    cache-write paths so the bypass is symmetric.

What did NOT change:
  - Stripe-shape contract for stable outcomes (success + quota_exceeded +
    upgrade_required + provision_limit_reached etc.) — those still cache.
  - 409 idempotency_key_conflict envelope (BUG-013/406) unchanged.
  - No new endpoints, no new fields, no auth changes.

Surface checklist (rule 22):
  - api/internal/middleware/idempotency.go                 helper + 2 wires
  - api/internal/middleware/idempotency_mutable_cache_test.go new regression
  - dashboard / marketing / OpenAPI                        no surface change
                                                           (Stripe contract preserved;
                                                            response shape unchanged)

Coverage block:
  Symptom:        Idempotent retry replays stale 402 after user clears recycle gate
  Enumeration:    rg -F 'rdb.Set(context.Background(), cacheKey' internal/middleware/idempotency.go
  Sites found:    2 cache-write paths (explicit + fingerprint)
  Sites touched:  2 / 2
  Coverage test:  TestShouldCacheResponse_MutableErrorsSkipCache iterates the
                  live mutableErrorCodes map (rule 18 — registry-iterating, not
                  hand-typed); TestIdempotency_RecycleGate402_SourceAssertion
                  static-grep that BOTH branches invoke shouldCacheResponse (rule 16).
  Live verified:  pre-merge curl evidence pending — see PR body

Local gate:
  - go build ./...                                          PASS
  - go vet ./...                                            PASS
  - go test ./internal/middleware/                          PASS (full suite)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>